package co.edu.unal.bioingenium.kbmed.knowledge.services.api;

import java.util.List;
import java.util.Set;
import javax.jws.WebService;

/**
 * 
 * @author Alejandro Riveros Cruz Riveros Cruz
 */
@WebService
public interface KnowledgeWebService {

    /**
     * Returns the names of the available semantic similarity measures
     * @return A String set 
     */
    Set<String> getSemanticSimilarityNames();

    /**
     * The conceptId for the given descriptorId
     * @param descriptorId 
     * @return conceptId
     */
    String getConceptIdForDescriptorId(String descriptorId);

    /**
     * Returns the term for the given descriptorId
     * @param descriptorId 
     * @return term
     */
    String getTermForDescriptorId(String descriptorId);

    /**
     * Returns the set of terms for a given conceptId
     * @param conceptId 
     * @return A set of terms
     */
    Set<String> getTermsByConceptId(String conceptId);

    /**
     * Returns the category for a given conceptId
     * @param conceptId 
     * @return category
     */
    String getCategoryForConceptId(String conceptId);

    /**
     * Returns the category for a given descriptorId
     * @param descriptorId 
     * @return category
     */
    String getCategoryForDescriptorId(String descriptorId);

    /**
     * Returns the path to the hierarchy root for the given conceptId in the given category
     * @param conceptId 
     * @return A list of conceptIds
     */
    List<String> getPathToRootByConceptId(String conceptId);

    /**
     * Returns the path to the hierarchy root for the given descriptorId in the given category
     * @param descriptorId 
     * @return A list of conceptIds
     */
    List<String> getPathToRootByDescriptorId(String descriptorId);

    /**
     * Returns the parents for the given conceptId in the given category
     * @param conceptId 
     * @return A set of conceptIds
     */
    Set<String> getDirectParentsByConceptId(String conceptId);

    /**
     * Returns the parents for the given descriptorId in the given category
     * @param descriptorId 
     * @return A set of conceptIds
     */
    Set<String> getDirectParentsByDescriptorId(String descriptorId);

    /**
     * Returns the childrens for the given conceptId in the given category
     * @param conceptId 
     * @return A set of conceptIds
     */
    Set<String> getDirectChildrensByConceptId(String conceptId);

    /**
     * Returns the childrens for the given descriptorId in the given category
     * @param descriptorId 
     * @return A set of conceptIds
     */
    Set<String> getDirectChildrensByDescriptorId(String descriptorId);

    /**
     * Returns the siblings for the given conceptId in the given category
     * @param conceptId 
     * @return A set of conceptIds
     */
    Set<String> getDirectSiblingsByConceptId(String conceptId);

    /**
     * Returns the siblings for the given descriptorId in the given category
     * @param descriptorId 
     * @return A set of conceptIds
     */
    Set<String> getDirectSiblingsByDescriptorId(String descriptorId);

    /**
     * Returns the neighbors(Parents,Childrens and Siblings) for the given conceptId in the given category
     * @param conceptId 
     * @return A set of conceptIds
     */
    Set<String> getNeighborsByConceptId(String conceptId);

    /**
     * Returns the neighbors(Parents,Childrens and Siblings) for the given descriptorId in the given category
     * @param descriptorId 
     * @return A set of conceptIds
     */
    Set<String> getNeighborsByDescriptorId(String descriptorId);

    /**
     * Returns the similarity value between the given concepts, measured by the given similarity function, the given concepts must be contained in the same hierarchy
     * @param conceptId1 
     * @param semanticSimilarityFunction 
     * @param conceptId2 
     * @return A double between 0 and 1
     */
    float getSemanticSimilarityByConceptId(String conceptId1, String conceptId2, String semanticSimilarityFunction);

    /**
     * Returns the similarity value between the given descriptors, measured by the given similarity function, the given concepts must be contained in the same hierarchy
     * @param descriptorId1 
     * @param descriptorId2 
     * @param semanticSimilarityFunction 
     * @return A double between 0 and 1
     */
    float getSemanticSimilarityByDescriptorId(String descriptorId1, String descriptorId2, String semanticSimilarityFunction);

    /**
     * Returns the similarity value between the given concepts, measured by the given similarity function, the given concepts must be contained in the same hierarchy
     * @param conceptIds 
     * @param semanticSimilarityFunction 
     * @return An array of doubles between 0 and 1
     */
    float[] getSemanticSimilaritysByConceptIds(List<String> conceptIds, String semanticSimilarityFunction);

    /**
     * Returns the similarity value between the given descriptors, measured by the given similarity function, the given concepts must be contained in the same hierarchy
     * @param descriptorIds 
     * @param semanticSimilarityFunction 
     * @return An array of doubles between 0 and 1
     */
    float[] getSemanticSimilaritysByDescriptorIds(List<String> descriptorIds, String semanticSimilarityFunction);
}
